Skip to content

/v2/custom-actions/{custom_action_id}/
Stable

Request

⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.

Updates an existing custom action by ID, modifying any combination of its name, type, state, placement, properties, and options. Accepts a CustomActionUpdate body where all fields are optional — only the fields provided will be updated. If options is included, it fully replaces the existing options list. Returns the updated CustomActionRead object on success. Returns 400 if the update is invalid (e.g., an invalid state transition) or 409 if the new name conflicts with an existing custom action.

About Update Custom Action

Custom action updates follow partial-update semantics for most fields, but options is a full replacement — supplying it overwrites all existing options and their associated scripts. State transitions follow lifecycle rules: only active custom actions can be deployed to Linux devices. Moving an action from active to inactive or draft will prevent it from being used in new Blueprint deployments.

Key Fields

custom_action_id — UUID of the custom action to update (path parameter, required)

name — Updated display name (1–50 characters; must remain unique within the tenant)

type — Updated UI component type: button, toggle, radio, or dropdown

state — Updated lifecycle state: draft, active, or inactive; only active actions are deployable

position_in_blueprints — Updated Blueprint section placement

position_in_device_settings — Updated device Quick Actions placement

properties — Replacement object for description, info_message, and tooltip_message

options — Replacement list of options; each option requires label, key UUID, and scripts.linux with script and interpreter; timeout_in_mins (integer, 2–35791394) is optional and sets the maximum script runtime in minutes

Common Use Cases

Activate a draft custom action by updating state to active when it's ready for deployment

Update script content by supplying a new options array with revised scripts

Rename or reposition a custom action within Blueprint sections

Best Practices

Retrieve the current state of the action with GET /v2/custom-actions/{custom_action_id}/ before updating to avoid unintentional changes

When updating options, include all options you want to retain — the list is fully replaced, not merged

Validate state transitions: moving from active to inactive may affect Blueprints currently referencing this action

Workflow

Retrieve the current action with GET /v2/custom-actions/{custom_action_id}/

Build a CustomActionUpdate payload with only the fields you intend to change (or a full options replacement if updating scripts)

Submit PUT /v2/custom-actions/{custom_action_id}/

Confirm the response reflects the updated fields and review the new updated_at timestamp

Path
custom_action_idstring, (uuid)required
Bodyapplication/jsonrequired
namestring, [ 1 .. 50 ] characters

Custom action name

typestring

The UI component type for this custom action

Enum:"button""toggle""radio""dropdown"
statestring

The current operational state of the custom action

Enum:"draft""active""inactive"
position_in_blueprintsstring

The location in the blueprint where the custom action will be added

Enum:"none""blueprints_apps_and_configuration""blueprints_connectivity""blueprints_device_security""blueprints_display_and_branding""blueprints_esper_settings""blueprints_scripts""blueprints_files""blueprints_platform_services""blueprints_hardware_settings"
position_in_device_settingsstring

The location in the device's Quick Actions where the custom action will be added

Enum:"none""device_quick_settings"
propertiesobject

Object for the description, info_message, and tooltip_message. Replaces the existing properties.

optionsArray of objects(blueprints_optionsRequest)

A new list of options to replace the existing ones

cURL
curl -i -X PUT \
  'https://api.esper.io/_mock/openapi/v2/custom-actions/{custom_action_id}/' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "type": "button",
    "state": "draft",
    "position_in_blueprints": "none",
    "position_in_device_settings": "none",
    "properties": {},
    "options": [
      {
        "label": "string",
        "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e",
        "scripts": {
          "linux": {
            "script": "string",
            "interpreter": "bash",
            "timeout_in_mins": 2
          }
        }
      }
    ]
  }'

Responses

Success

Bodyapplication/json
contentobject(blueprints_CustomActionRead)
messagestring
codeinteger
Value:200
Response
{
  "content": {
    "name": "string",
    "type": "button",
    "state": "draft",
    "position_in_blueprints": "none",
    "position_in_device_settings": "none",
    "properties": {},
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "options": [ … ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": 0,
    "updated_by": 0
  },
  "message": "string",
  "code": 200
}